home *** CD-ROM | disk | FTP | other *** search
/ Ian & Stuart's Australian Mac 1993 September / September 93.iso / Archives / Applications / Text / Text Editors / Alpha 5.31 Folder / Help / Alpha Tcl Extensions < prev    next >
Encoding:
Text File  |  1993-02-13  |  17.1 KB  |  323 lines  |  [TEXT/ALFA]
  1. ==============================================================================
  2. = Alpha's Additional Tcl Commands
  3. ==============================================================================
  4.  
  5. In this list of routines, text between '<' and '>' is a placeholder for a 
  6. required parameter, text between '[' and ']' is a placeholder for an 
  7. optional parameter, and the '|' signifies a choice of two alternatives. A 
  8. '+' signifies that the previous symbol can be present one or more times, 
  9. while a '*" means zero or more times. 
  10.  
  11. The following are Alpha-specific tcl routines:
  12.  
  13. • addMenuItem [-m] [-l <meta-characters>] <menu name> <item name> - Convert
  14.   item to menu form and add to specified menu. If '-m' specified, menu 
  15.   form conversion not done. The '-l' option allows you to use menu meta 
  16.   characters as text of menu items. If the '-l' option is used, the 
  17.   <meta-characters> string is interpreted for menu item attributes, and 
  18.   meta-characters in <item name> are included in the menu item text 
  19.   literally. For example: 
  20.       addMenuItem -m -l "/B" "Hello/C" 
  21.   would appear as the text "Hello/C" in the menu, and have "B" as its 
  22.   command equivalent.
  23. • alertnote message_string
  24.   This command will display message_string in a standard Macintosh alert box.
  25. • ascii (see bindings).
  26. • askyesno prompt
  27.   This command will display a Macintosh alert box with promptdisplayed 
  28.   with the push buttons Yes, No, Cancel. The command will return the 
  29.   string "yes", "no", or "cancel".
  30. • beep
  31. • bind  (see bindings)
  32. • blink <pos> - blink cursor at 'pos'
  33. • breakIntoLines <string> - return 'string' with 
  34.   carriage returns and spaces inserted to satisfy 
  35.   'leftFillColumn' and 'fillColumn' variables.
  36. • bringToFront <winName> - Bring named window to front.
  37. • cd [directory]
  38.   This command will set the current working directory to "directory". The directory 
  39.   argument may or may not end with a colon. The working directory is the directory 
  40.   in which file names that contain no colons (folders) will be located with file related 
  41.   commands. No argument means Alpha's home directory.
  42. • colors <fore red> <fore green> <fore blue> <back red> <back green> <back blue>
  43. • cp <fromName> <toName> [force]
  44.   This command will copy the file fromName and name the new file toName. If 
  45.   toName includes a path name that is different from the path in fromName, the copy 
  46.   will be made in a new directory (specified by toName). The copy can be made 
  47.   across volume (disk drives). The force option indicates that the copy should 
  48.   overwrite any existing file with the same name as toName. This command copies 
  49.   both data forks, and the Finder information.
  50. • createTMark <name> <pos> - create a temporary 'mark' 
  51.   at location 'pos'. 
  52. • ctime <time>
  53.   This command will return a UNIX time string of the format "Wed Feb 19 
  54.   22:43:36 1992". The parameter time is in Macintosh seconds, and would be the 
  55.   result of a now or file mtime command or the like.
  56. • deleteMenuItem [-m] <menu name> <item name> - Convert item to menu form 
  57.   and delete from specified menu. If '-m' specified, menu form conversion 
  58.   not done. 
  59. • deleteText <pos1> <pos2> - remove text between 'pos1' 
  60.   and 'pos2'
  61. • displayMode <mode> - Up to four characters of the 'mode' string are 
  62.   displayed in the status line at the bottom of a window.
  63. • dosc <-c 'sign' | -n appName> <-s string | -f fileName> <[-t timeout]|[-r]>
  64.   Send a 'misc' 'dosc' AppleEvent. Options are the following:
  65.    -c 'sign' 
  66.            "sign" is a four-letter creator signature of a running application.
  67.    -n appName
  68.            "appName" is the name of a running application.
  69.    -s string
  70.            "string" is the text of a script to send to the other app.
  71.    -f fileName
  72.            "fileName" is the complete or relative pathname of a file the other 
  73.            application should execute.
  74.    -t timeout
  75.            "timeout" is the number of ticks Alpha should wait for a response. A 
  76.            timeout of "0" means wait forever.
  77.    -r
  78.            Do not wait for reply.
  79.    If neither of the '-c' and '-n' options is chosen, the PPC Browser is 
  80.    used. Either '-s' or '-f' must be chosen. Thus, you can have "Alpha 
  81.    5.02" and "Alpha 5.02 Copy" sending Apple events to each other, or they 
  82.    can send events to a remote server such as Apple's ToolServer. 
  83.    "$HOME:Tcl:UserCode:createStuffitArchive.tcl" contains examples of 
  84.    controlling Stuffit Deluxe via this command.
  85.  
  86. • echo <string> [<string>...] - echo the strings (used 
  87.   in shells).
  88. • edit <name> [-r] [-m] - Open a file in a new window. '-r' means open 
  89.   the file read-only. '-m' means omit the function titlebar menu and  
  90.   present only the marks titlebar menu, which is labeled with the 
  91.   contents of 'markLabel'.
  92. • get_directory
  93.   This command will display a standard Macintosh file dialog and request the user 
  94.   select a folder. The command will return the selected folder's full path name, or an 
  95.   empty string if the Cancel button was selected.
  96. • getenv <varname>
  97.   This command will return the value of the environment variable varname. 
  98.   Environment variables are initialized by reading the file •tclenv. The environment 
  99.   file has the format varname=value as in the following example:
  100.  
  101.     TERM=vt100
  102.     TCLINIT=::tcl:TclInit.tcl
  103.     TCLDEFAULT=
  104.     TEST=TEST
  105.     TCLPATH=::tcl:tclsh:tclsrc
  106.  
  107. • getfile <prompt>
  108.   This command will display an SFGetFile() and return the full path name of the 
  109.   selected file, or an empty string if CANCEL button was selected.
  110. • getfinfo <fileName>
  111.   This command will display the standard Macintosh file information in the form:
  112.   "'aeQL' 'QUIL' lvbsIdm 02/17/92 23:57:12 02/19/92 22:43:36 0,156 219 0".
  113.   The fields are the fdCreator, fdType, fdFlags, flCreationDate, flCreationtime, 
  114.   flModDate, flModTime, fdLocation.H,V, dataForlLength, rsrcForkLength, 
  115.   respectively. The fdFlags field uses characters to represent bits:
  116.     l/L    not locaked/Locked
  117.     v/V    visible/notVisible
  118.     b/B    not bundled/Bundled
  119.     s/S    not system/System
  120.     i/I    not initialized/Initialized
  121.     d/D    not desktop/Desktop
  122.     m/M    not sharable/sharable
  123. • getGeometry - return a TCL list containing the left 
  124.   edge of the current window, the top, the width, and
  125.   height.
  126. • getline <prompt> <default>
  127.   This command will display a Macintosh alert box with prompt displayed, a 
  128.   text edit field with default initially in the field, and with the push 
  129.   buttons OK, Cancel.. The command will return the text entered into the 
  130.   text edit field by the user, or an empty string if the user selected the 
  131.   Cancel button. 
  132. • getMainDevice - return a list containing the left, top, right, and 
  133.   bottom of the rectangle defining the main device.
  134. • getMark - return the current mark.
  135. • getPathName - prompt the user with an SFGetFile dialog and return 
  136.   complete pathname.
  137. • getPos - return the current insertion point
  138. • getSelect - return the currently selected text, if 
  139.   any.
  140. • getTMarks - Return a list of temporary marks. Each item of the returned 
  141.   list is a sublist containing the mark name, the complete pathname of the 
  142.   mark, and the start and finish of the selection named by the mark. The 
  143.   following is an example of the result: 
  144.  
  145.     {{temp1 External:file.c 1312 1315} {temp2 Internal:it.h 111 111}} 
  146.  
  147. • getText <pos1> <pos2> - return the text between 'pos1' 
  148.   and 'pos2'.
  149. • glob [-i] [-t <TYPE>] [-c <CRTR>]
  150.   The original glob provided by the UNIX version of tcl was not quite 
  151.   adequate for the more complex Macintosh file system. Issues such as 
  152.   invisible file handling, Finder type and creator filtering, and space 
  153.   handling in file names. Release 6 of tcl has dealt with the original 
  154.   problem with spaces in filenames, but the following options are provided 
  155.   to deal with additional Macintosh issues. 
  156.  
  157. Anyhow, the new glob now takes several options. They are:
  158.     -i    This option causes glob to list invisible files also.
  159.     -t TYPE    This option causes glob to only list file with the 
  160.         indicated Finder file typeTYPE. This option may be 
  161.         used with the -c option.
  162.     -c CRTR    This option causes glob to only list file with the 
  163.         indicated Finder file creatorCRTR. This option may 
  164.         be used with the -t option.
  165.         Also note that the original glob would skip dot files
  166.         (i.e., file names the begin with a period) 
  167.         in the listing, unless the pattern began with a period.
  168.         Tickle extends this concept one step further on the
  169.         Macintosh, and skips spot files (i.e., file names that 
  170.         begin with '•'), unless the pattern starts with a spot.
  171. • goto <pos> - goto the position 'pos'.
  172. • gotoTMark <name> - goto the temporary mark 'name'.
  173. • enableMenuItem <menuName> <item text> <on|off> - Either enable or 
  174.   disable the menu item of user menu 'menuName' that has text '<item 
  175.   text>'. Note that unless the menu is not only created, but also already
  176.   inserted, this command has no effect. 
  177. • icon [-f <winName>] [-c|-o|-t|-q] [-g <h> <v>] - Having to do w/ 
  178.   iconifying windows. '-c' means close (iconify) window, '-o' open, '-t' 
  179.   toggle open/close, '-q' returns either a '1' for an iconified window or a 
  180.   '0' for an uniconified window, and '-g' moves the icon to horizontal 
  181.   position <h> and vertical position 'v'. Options are executed as they 
  182.   are parsed, so the '-f' option, if present, should always be first. 
  183. • insertMenu <name> - insert the previously created user menu 'name' into 
  184.   the menuBar. 
  185. • insertText [-w <win name>] <text> [<text>]... - Insert 'text' at the current 
  186.   insertion point.
  187. • launch -f <name> - launch the named app into the background. Note that 
  188.   for some yet unexplained reason, some applications (MicroSoft Word) 
  189.   won't launch completely in the background. 'launch'ing such 
  190.   applications won't insert the application into any system menu that 
  191.   specifies running applications (although "About the Finder..." will 
  192.   list it. The only way to get to such an app is through Alpha's 
  193.   'switchTo', after which the application will finish launching. The '-f' 
  194.   option gets around this by launching the application in the foreground 
  195.   instead.
  196. • lineStart <pos> - return the position of the start of
  197.   the line 'pos' is on.
  198. • listpick [-p <prompt>] <list>
  199.   This command will display a dialog with the list displayed in a List Manager list. If 
  200.   the user presses the Cancel button, an empty string is returned. If the user selects 
  201.   the Open button, or double clicks an item in the list, that item will be returned.
  202. • lookAt [-w <name>] <pos> - return the 'pos'th character of the 
  203.   current file, or the file named by <name> if the '-w' option is specified.
  204. • markMenuItem <menuName> <item text> <on|off> - Either mark or unmark
  205.   the menu item of user menu 'menuName' that has text '<item text>'. 
  206.   Note that unless the menu is not only created, but also already
  207.   inserted, this command has no effect. 
  208. • matchIt <brace char> <pos> - Return pos of matching brace. Recognizes 
  209.   parenthesis, square brackets, and curly braces.
  210. • maxPos - returns the number of characters in the front
  211.   window.
  212. • menu [-n <name>] [-m] [-p <procname>] <list of menu items> - Defines a 
  213.   new menu named 'name' (if provided w/ '-n' option). The menu is not yet 
  214.   inserted into the menubar. The menu commands may be nested for 
  215.   heirarchical menus, see 'AlphaBits.tcl' for examples. Alpha massages the 
  216.   function names to make them look better in the menus. 
  217.   '-n <name>'    Name the menu. Not necessary for submenus.
  218.   '-m'            No menu form. If not supplied, each menu item is split into 
  219.                   words at each capitalized letter.
  220.   '-p <name>'     The tcl proc named by 'name' is called w/ the menu item's 
  221.                   contents as it's single argument when the item is chosen. If the 
  222.                   proc returns "normal" as its result, the menu item is executed as 
  223.                   if no proc had been specified.
  224. • message <string> - prints 'string' on the status line.
  225. • mkdir <name> - creates a directory (folder) named 
  226.   'name' in the current directory.
  227. • moveWin [win name] <left> <top> - moves current or specified window.
  228. • mtime <time> [long|short|abbrev]
  229.   Returns a date and time string using the Macintosh International Utilities. The 
  230.   long/short/abbrev specification corresponds to the date. These are the following 
  231.   formats:
  232.     short        3/16/92 9:20:46 PM
  233.     abbrev    Mon, Mar 16, 1992 9:20:49 PM
  234.     long        Monday, March 16, 1992 9:20:43 PM
  235. • mv <fromName> <toName> [force]
  236.   This command will move the file fromName to toName. If toName includes a path 
  237.   name that is different from the path in fromName, the file will be moved into a new 
  238.   directory (specified by toName). The move can not be made across volume (disk 
  239.   drives). The force option indicates that the move should overwrite any existing file 
  240.   with the same name as toName.
  241. • nextLineStart <pos> - return the position of the start 
  242.   of the next line after position 'pos'.
  243. • now
  244.   Returns the current time as Macintosh seconds. This is the number of seconds that 
  245.   have elapsed since Midnight Jan 1, 1904. Appropriate for input to ctime.
  246. • posToRowCol <pos> - converts from absolute position to row, col.
  247. • prompt <prompt> <default> [<name> <menu item>...] - prompt dialog to 
  248.   the user with a prompt string and a default value. The prompt dialog can 
  249.   optionally include a popup menu specified by 'name' and the succeeding 
  250.   strings. Selection of the popup menu items inserts the item text into the 
  251.   editable dialog item. 'Prompt' returns the value of the editable item. 
  252.   If the 'Cancel' button is selected, the tcl returns an error and your 
  253.   script will be stopped unless you execute the command from 'catch'.
  254. • putenv <varname> <value>
  255.   This command will set the environment variable varname to value.
  256. • putfile <prompt> <original>
  257.   This command will display an SFPutFile() and return the full path name of the 
  258.   selected file, or an empty string if CANCEL button was selected. Original is the 
  259.   default name displayed for the user.
  260. • pwd
  261.   This command will return the current working directory.
  262. • removeMenu <name> - remove menu 'name' from menubar.
  263. • removeTMark <name> - remove temporary mark.
  264. • replaceText <pos1> <pos2> [text]+ - replaces the text
  265.   between 'pos1' and 'pos2' with 'text', where 'text' can be any number 
  266.   of arguments.
  267. • rm <fileName>
  268.   This command will delete the file fileName.
  269. • rowColToPos <row> <col> - converts to abosolute position.
  270. • search [-f <num>] [-r <num] [-i <num>] [-m <num] [-n] [-l <limit>] <pattern> <pos> - 
  271.   Searches for 'pattern' from position 'pos'. The '-f', '-r', '-i', and 
  272.   '-m' options allow the 'forward', 'regExpr', 'ignoreCase', and 
  273.   'matchWord' internal variables to be set. The '-l' option allows a search 
  274.   limit to be set. The search fails if the a match is not found totally 
  275.   contained between 'pos' and 'limit'. The '-n' option specifies that a 
  276.   failed search still returns TCL_OK. However, the result of the call is 
  277.   then just an empty string. If the search succeeds, a list of two 
  278.   positions will be returned. The first is the starting position of the 
  279.   match, the second is one past the last character. 
  280. • select <pos1> <pos2> - selects the text between 'pos1' 
  281.   and 'pos2'.
  282. • selEnd - returns the end of the hilited selection, or 
  283.   the current insertion point if no text is selected.
  284. • sendToBack <winName> - Sent named window to back.
  285. • setfinfo <fileName> [-a flags] [-c fdCreator] [-t fdTypes]
  286.   This command will set the standard Macintosh file information. The flags setting 
  287.   must be of the same format as displayed by the getfinfo flag.
  288. • shadowVar <name> - Associates a Tcl variable with an Alpha variable of 
  289.   the same name. Writes to the Tcl variable automatically are copied to 
  290.   the Alpha variable.
  291. • sizeWin [win name] <width> <height> - sets size of current or specified window.
  292. • substituteVars <string> - Takes a single string and
  293.   substitutes for all variables inside it, regardless of
  294.   depth. Unfortunately, you currently need to make 'global var' 
  295.   declarations in the proc you call this for each 'var' that might need 
  296.   to be substituted in the string (see proc.tcl for examples).
  297. • switchTo <appName> - Switches to application 'appName'.
  298. • tclResult - displays a dialog showing the result of 
  299.   the last TCL evaluation.
  300. • ticks
  301.   Returns the current TickCount. Ticks are 60ths of a seconds. TickCount is the 
  302.   number of ticks since the Macintosh was started. The command:
  303.         puts stdout [expr "[ticks] / 60"]
  304.   will print the number of seconds since the Macintosh was booted.
  305. • traceFunc on <funcName> <winName> Trace 'funcName', send output to 
  306.                                     'winName'. 
  307.   traceFunc off                        Turn function tracing off.
  308.   traceFunc status                    Display current tracing status.
  309. • version - Return string of the form "Alpha Version 5.31, Feb. 15, 1993".
  310. • watchCursor - turns the cursor into a a watch cursor.
  311. • winNames [-f] - return a TCL list of all open windows. If '-f' option 
  312.   specified, complete pathnames are returned.
  313. • wrapText
  314. • xtclcmd [-f filename] <cmdname> [argument_list]...
  315.   This command will load the external command cmdname and pass it the argument 
  316.   list [ cmdname argument_list... ]. External command are code resources of type 
  317.   XTCL. They may be located in the resource fork of the tickle application, or they 
  318.   may be located in a file named XTCL File in the same directory as the tickle 
  319.   application. If the optional -f filename is included, the external command will first 
  320.   be loaded from filename before the other two files.
  321.   See the appendix for a detailed description of the external tcl command interface. 
  322.   See the accompanying sources for an example of writing an XTCL.
  323.